<html>
<h2>ProSound Playbackdriver Interface</h2>

The playback driver interface allows ProSound to output samples through whatever hardware may be available in the future.<br>

The playback drivers are fxs which (during initialisation) install themselves as playback drivers by calling the ProSound_PlaybackDriver code.


<h4>ProSound_PlaybackDriver</h4>
This code installs a playback driver.

<pre>
On entry
        R0  =   0 (install)
        R1  =>  PDB (playback driver block)
                +0      Offset to install code
                +4      Offset to de-install code
                +8      Offset to prepare code
                +12     Offset to init code
                +16     Offset to kill code
                +20     Offset to play start code
                +24     Offset to play stop code
                +28     Offset to play pause code
                +32     Offset to play mute code
                +36     Offset to status code
                +40     Offset to fill buffer code
                +44     Offset to position code
                +48     Flags
                        Bit 0-1      <number of channels>-1
                        Bit 2 set => do not multitask
                        Bit 3 set => playbackdriver is disabled
                        Bit 4 set => playback uses LOADs of CPU time
                        Bit 8-10     see note about Workspace
                        Bit 11-13    see note about Workspace
                +52     Offset to name
                        (ProSound_PlaybackDriver changes all offsets
                        to pointers)

 On exit
        R0  =   0 (installed OK) or <> 0 (not installed)
</pre>


<h4>Playback driver block</h4>

<pre>
Word 0          Install code
                This is called when the user selects the playback driver.
                On entry
                        R5  =>  PDB
                On exit
                        R0  =   0 (installed OK)
                    or  R0  =>  error block

                The de-install code for the previously selected driver is
                called before the install code for the new driver is called.
                If the new driver cannot install, the previous driver is
                re-installed.

 Word 1         De-install code
                This is called when the user selects another playback driver.
                On entry
                        R5  =>  PDB

 Word 2         Prepare code
                This is called to inquire the playback driver how much
                memory it requires.
                On entry
                        R0  =   Playback frequency
                        R2  =   Minimum buffer size (samples/channel)
                        R5  =>  PDB
                On exit
                        R0  =   Number of bytes of buffer workspace needed

                The playbackdriver may use a larger buffer than that
                specified in [R2] but the fill code must be able to handle
                up to [R2] samples per channel.

 Word 3         Init code
                This is called to initialise the playback driver
                On entry
                        R0  =   Playback frequency
                        R1  =>  Buffer workspace
                        R2  =   Minimum buffer size (samples/channel)
                        R3  =   Flags (as set in ProSound$Options)
                        R5  =>  PDB
                On exit
                        R0  =   0 (initialised OK)
                    or  R0  =>  error block

 Word 4         Kill code
                This is called after playback has stopped, before the
                workspace is released
                        R5  =>  PDB

 Word 5         Play start code
                This is called to start playback
                On entry
                        R5  =>  PDB

 Word 6         Play stop code
                This is called to stop playback and reset hardware etc.
                The play mute and play pause code is called before this, to
                avoid any ugly 'clicks'
                On entry
                        R5  =>  PDB

 Word 7         Play pause code
                This is called to pause or restart playback
                On entry
                        R0  =   0 to pause
                   or   R0  =   1 to restart
                        R5  =>  PDB

 Word 8         Play mute code
                On entry
                        R0  =   0 (to mute playback)
                   or   R0  =   1 (to 'un'-mute playback)
                   or   R0  =   2 (to mute by flushing buffers (see Notes))
                                other values of R0 must be ignored
                        R5  =>  PDB

 Word 9         Read status code
                This is called to read whether the buffer is empty
                On entry
                        R5  =>  PDB
                On exit
                        R0  =   0 if the buffer is full
                   or   R0  >   0 if the buffer is empty

 Word 10        Fill buffer code
                This is called to fill the playback buffer(s)
                On entry
                        R0  =>  Wordaligned buffer holding samples
                        R1  =   Number of samples in the buffer
                                Stereo samples are interleaved LRLRLRL...
                        R5  =>  PDB

 Word 11        Read position code
                This is called to read how many samples have been played
                so far
                On entry
                        R5  =>  PDB
                On exit
                        R0  =   Samples played so far (per channel)

 Word 12        Flags

 Word 13        Offset to playback driver name (max 24 chars)
</pre>



<h6>Mute</h6>
The playback driver need not support 'mute by flushing buffers', but may instead treat this as a 'normal' mute.


<h6>Multitasking</h6>
All entrypoints will be called only when ProSound is paged in.


<h6>Workspace</h6>
When playback is singletasking, bits 8-10 in the flags control from where the driver allows the workspace to be allocated:
<pre>
        Bit 8 clear  =>  RMA is legal
        Bit 9 clear  =>  application workspace is legal
        Bit 10 clear =>  a dynamic area is legal
</pre>
When playback is multitasking, bits 11-13 in the flags control from where the driver allows the workspace to be allocated:
<pre>
        Bit 11 clear =>  RMA is legal
        Bit 12 clear =>  application workspace is legal
        Bit 13 clear =>  a dynamic area is legal
</pre>
If possible, the memory will be taken from a dynamic area. RMA is the last resort.


<h6>Multiple drivers</h6>
ProSound allows multiple playbackdrivers to be installed at the same time (eg. a mono and a stereo playbackdriver) but two playback drivers which support the same number of channels cannot be installed at the same time.


<h6>Channels</h6>
Currently only 1 or 2 channels are allowed.


<h6>Dying</h6>
When ProSound quits, it calls the fx kill code, but NOT the playback driver de-install code; thus the fx kill code should call the playback driver de-install code if the playback driver claims memory, opens files etc.


<h6>Multiple calls</h6>
A playback driver should allow the kill code to be called even if the playback driver isn't currently playing. Likewise, the de-install, play and stop entry points may be called more than once.
